<html>

<!-- Mirrored from bos.asmhackers.net/docs/booting/docs/tutorial_03.htm by HTTrack Website Copier/3.x [XR&CO'2013], Tue, 07 Oct 2014 11:22:00 GMT -->
<head>

</head>
<body margin-left=180px>
	<h1>Mixing Assembly and C-code</h1><br>

	<h2 class="header">Why mix programming languages?</h2>

	<h2>After the last tutorial, you now feel like king of the world! =) You're eager to jump into the action, but there's one problem. Even though assembly is a powerful language, it takes time to read, write and understand. This is the main reason there ARE more programming languages than just assembly =).<br><br>

	Now that we have a working 32-bit boot sector, we want to be able to continue our development in a higher language, whenever possible. C is my main choice, because it's common and powerful. If you think C is old and want to use C++ instead, I'm not stopping you. The choice is your's to make.<br><br>

	Say that we want a print() function instead of addressing the video memory directly. Also, we want a clrscr() to clear the screen. This could easily be done by making a for-loop in C. We can't make function calls from a binary file (eg. our boot sector). For this purpose, we create another file, from which we will operate after the boot sector is done. So now we need to create a file, called '<i>main.c</i>'. It will contain the main() function - yes, even operating systems can't escape main() =). As I said, a boot sector can't call functions. Instead, we read the following sector(s) from the boot disk, load it/them into memory and finally we jump to the memory address. We can do this the hard way using ports or the easy way using the BIOS interrupts (when we're still in Real mode). I choose the easy way, as always.<br><br><br></h2>

	<h2 class="header">How do I do this?</h2>

	<h2>We start as always, by creating a file (<i>bootsect.asm</i>) and typing:</h2>

		<h4>[BITS 16]<br><br>
		[ORG 0x7C00]</h4>

	<h2>When the BIOS jumps to our boot sector, it doesn't leave us empty handed. For example, to read a sector from the disk, we have to know what disk we are resident on. Probably a floppy disk, but it could as well be one of the hard drives. To let us know this, the BIOS is kind enough to leave that information in the <i>DL register</i>.<br><br>

	To read a sector, the INT 13h is used. First of all, we have to 'reset' the drive for some reason. This is just for security. Just put 0 in AH for the RESET-command. DL specifies the drive and this is already filled in by our friend, the BIOS. The INT 13h returns an error code in the AH register. This code is 0 if everything went OK. We assume that the only thing that can go wrong, is that the drive was not ready. So if something went wrong, just try again.</h2>

		<h4>reset_drive:</h4>
			<h5>mov ah, 0<br>
			int 13h<br>
			or ah, ah<br>
			jnz reset_drive</h5>

	<h2>The INT 13h has a lot of parameters when it comes to reading and loading a sector from the disk to the memory. This table should clearfy them a bit.<br><br>

	<table border=1>
		<tr><td><b>Register</b></td><td><b>Function</b></td></tr>
		<tr><td>ah</td><td>Command - 02h for 'Read sector from disk'</td></tr>
		<tr><td>al</td><td>Number of sectors to read</td></tr>
		<tr><td>ch</td><td>Disk cylinder</td></tr>
		<tr><td>cl</td><td>Disk sector (starts with 1, not 0)</td></tr>
		<tr><td>dh</td><td>Disk head</td></tr>
		<tr><td>dl</td><td>Drive (same as the RESET-command)</td></tr>
	</table><br>


	Now, where shall we put our boot sector. We have the whole memory by our selves. Well, not the reserved parts, but almost the whole memory. Remember, we placed our stack in 090000h-09FFFFh. I choose 01000h for our 'kernel code'. In real mode (we haven't switched yet), this is represented by 0000:1000. This address is read from es:bx by the INT 13h. We read two sectors, just in case our code happends to get bigger than 512 bytes (likely).</h2>

			<h5>mov ax, 0<br>
			mov es, ax<br>
			mov bx, 0x1000</h5>

	<h2>Followed by the INT 13h parameters and the interrupt call itself.</h2>

			<h5>mov ah, 02h<br>
			mov al, 02h<br>
			mov ch, 0<br>
			mov cl, 02h<br>
			mov dh, 0<br>
			int 13h<br>
			or ah, ah<br>
			jnz reset_drive</h5>

	<h2>Now, we should have the next sector on the disk in memory address 01000h. Just continue with the code from tutorial 2 with two little ajustments. First, now that we're going to clear the screen, we don't need our 'P' at the top right corner anymore. And instead of hanging the computer, we will now jump to our new C-code.</h2>

			<h5>cli<br>
			xor ax, ax<br>
			.<br>
			.<br>
			.<br>
			mov ss, ax<br>
			mov esp, 090000h</h5>

	<h2>Now, we want to jump to our code segment (08h) and offset 01000h. Remember, we didn't want our 'P' either. Change the following four lines:</h2>

			<h5>mov 0B8000, 'P'<br>
			mov 0B8001, 1Bh</h5><br>
		<h4>hang:</h4>
			<h5>jump hang</h5>

	<h2>To:</h2>

			<h5>jump 08h:01000h</h5>

	<h2>Don't forget to fill the rest of the file...</h2>

		<h4>gdt:<br><br>
		gdt_null:<br>
		.<br>
		.<br>
		.<br>
		times 510-($-$$) db 0</h4>
			<h5>dw 0AA55h</h5>

	<h2>Moving on to actually writing the second sector =). This should be our main(). Our main() function should be declared as void and not as int. What should it return the integer to?<br><br>
 	<i>(Updated section: Removed constant string and added a compile flag instead! Thanks to <b>Kip Warner</b>)</i><br>
	First of all, we wan to clear the screen, then we print our message and go into an infinite loop (hang). Simple as that.</h2>

		<h4>void main()<br>
		{</h4>
			<h5>clrscr();
			print(<i>"MuOS Tutorial 3"</i>);
			for(;;);</h5>
		<h4>}</h4>

	<h2><i>But wait a minute?! You haven't declared clrscr() or print() anywhere? What's up with that?</i> No, that's true. Because of my lack of knowledge of the linker, I don't know how to do that. This way, if we spelled everything right, the linker finds the appropriate function. If not, our OS will tripple fault and die/reset. Ideas are welcome here...<br><br>

	Now for our other functions. We place them in a file called '<i>video.c</i>'. clrscr() is the easy one, so let's start with that.</h2>

		<h4>void clrscr()<br>
		{</h4>

	<h2>We know that the video memory is resident at 0xB8000. So we start by assigning a pointer to that location.</h2>

			<h5>unsigned char *vidmem = (unsigned char *)0xB8000;</h5>

	<h2>To clear the screen, we just set the ASCII character at each position in the video memory to 0. A standard VGA console, is initialized to 80x25 characters. As I told you in tutorial 2, the even memory addresses contains the ASCII code and the odd addresses, the color attribute. By default, our color attributes should be 0Fh, white on black background, non-blinking. All we have to do, is to make a simple for-loop.</h2>

			<h5>const long size = 80*25;<br>
			long loop;<br><br>
			for (loop=0; loop&lt;size; loop++) {</h5>
				<h6>*vidmem++ = 0;<br>
				*vidmem++ = 0xF;</h6>
			<h5>}</h5>
			
	<h2>Now for the cursor position. If we cleared the screen, we also want our cursor to be in the top right corner. To change the cursor position, we have to use two assembly commands: <i>in</i> and <i>out</i>. The computer has <i>ports</i> which is a way to communicate with the hardware. If you want to learn more, have a look at Chapter 12 in Intel's <a href="http://muos.sourceforge.net/docs/24547011.pdf" target="_blank">first manual</a>.<br><br>

	It's a little tricky to change the cursor position. We have two ports: 0x3D4 and 0x3D5. The first one is a index register and the second a data register. This means that we specify what we want to read/write with 0x3D4 and then do the actual reading and/or writing from/to 0x3D5. This register is called CRTC and contains functions to move the cursor position, scroll the screen and some other things.<br><br>

	The cursor position is divided into two registers, 14 and 15 (0xE and oxF in hex). This is because one index is just 8 bits long and with that, you could only specify 256 different positions. 80x25 is a larger than that, so it was divided into two registers. Register 14 is the MSB of the cursor offset (from the start of the video memory) and 15 the LSB. We call a function out(unsigned short _port, unsigned char _data). This doesn't exist yet, but we'll write it later.</h2>

			<h5>out(0x3D4, 14);<br>
			out(0x3D5, 0);<br>
			out(0x3D4, 15);<br>
			out(0x3D5, 0);</h5>
		<h4>}</h4>

	<h2>Now, to write the out() and in() functions, we need some assembly again. This time, we can stick to C and use inline assembly. We put them in a seperate file called '<i>ports.c</i>'. First, we have the in() function.</h2>

		<h4>unsigned char in(unsigned short _port)<br>
		{</h4>

	<h2>This is just one assembly line, so if you want to know more about the in command, look in Intel's <a href="http://muos.sourceforge.net/docs/24547111.pdf" target="_blank">second manual</a>. Inline assembly is kind of special in GCC. First you program all your assembly stuff and then you specify inputs and outputs. We have one input and one output. The input is our port and the output is our value recieved from <i>in</i>.</h2>

			<h5>unsigned char result;<br>
			__asm__ ("in %%dx, %%al" : "=a" (result) : "d" (_port));<br>
			return result;</h5>
		<h4>}</h4>

	<h2>This looks rather messy, but I'll try to explain. The two %% says that this is a register. If we don't have any inputs or outputs, only one % is required. After the first ':', the outputs are lined up. The "=a" (result), tells the compiler to put result = EAX. If I'd write "=b" instead, then result = EBX. You get the point. If you want more than one output, just put a ',' and write the next and so on. Now to the outputs. "d" specifies that EDX = _port. Same as output, but without the '='. Plain and simple =).<br><br>

	Now to the out(). Same as for in(), but with no outputs and two inputs instead. I hope this speaks for itself.</h2>

		<h4>void out(unsigned short _port, unsigned char _data)<br>
		{</h4>
			<h5>__asm__ ("out %%al, %%dx" : : "a" (_data), "d" (_port));</h5>
		<h4>}</h4>

	<h2>Then we have the print(). Three variables are needed. One pointer to the videomemory, one to hold the offset of the cursor position and one to use in our print-loop.</h2>

		<h4>void print(const char *_message)<br>
		{</h4>
			<h5>unsigned char *vidmem = (unsigned char *)0xB8000);<br>
			unsigned short offset;<br>
			unsigned long i;</h5>

	<h2>We want print() to write at the cursor position. This is read from the CRTC registers with the in() function. Remember that register 14 holds bits 8-15, so there we need to left shift the bits we read. We increase the vidmem pointer by two times offset, because every character has both ASCII code and a color attribute.</h2>

			<h5>out(0x3D4, 14);<br>
			offset = in(0x3D5) << 8;<br>
			out(0x3D4, 15);<br>
			offset |= in(0x3D5);<br><br>

			vidmem += offset*2</h5>

	<h2>With a correct vidmem pointer, we're all set to start printing our message. First we initialize our loop variable <i>i</i>. The loop should execute as long as the value we are next to print, is non-zero. Then we simply copy the value into vidmem and increase vidmem by two (we don't want to change the color attribute).</h2>

			<h5>i = 0;<br>
			while (_message[i] != 0) {</h5>
				<h6>*vidmem = _message[i++];<br>
				vidmem += 2;</h6>
			<h5>}</h5>

	<h2>Our message is printed and all that is left to do is to change the cursor position. Again, this is done with out() calls.</h2>

			<h5>offset += i;<br>
			out(0x3D5, (unsigned char)(offset));<br>
			out(0x3D4, 14);<br>
			out(0x3D5, (unsigned char)(offset >> 8));</h5>
		<h4>}</h4>

	<h2>To compile, we start with the boot sector.</h2>

		<h4>nasmw -f bin bootsect.asm -o bootsect.bin</h4>

	<h2>For the rest of the C-files, we first compile each file seperatly and then link them together.</h2>

		<h4>gcc -ffreestanding <i>-fwritable-strings</i> -c main.c -o main.o</h4>
		<h4>gcc -c video.c -o video.o<br>
		gcc -c ports.c -o ports.o<br>
		ld -e _main -Ttext 0x1000 -o kernel.o main.o video.o ports.o<br>
		ld -i -e _main -Ttext 0x1000 -o kernel.o main.o video.o ports.o<br>
		objcopy -R .note -R .comment -S -O binary kernel.o kernel.bin</h4>

	<h2>'-i' says that the build should be incremental. First link without it, because when '-i' is used, the linker doesn't report unresolved symbols (misspelled function names for example). When it linkes without errors, put '-i' to reduce the size. '-e _main' specifies the entry symbol. '-Ttext 0x1000' tells the linker that we are running this code at memory address 0x1000. Then we just specify what output format we want, the output file name and list out .o-files, starting with main.o (important!). The objcopy line make the .o-file to a plain binary file, by removing some sections.<br><br>

	We're not done yet. We have our boot sector and our kernel. The boot sector assumes that the kernel is resident the two following sectors on the same disk. So, we need to make them into one file. For this, I've made a special program in C. I'm not going into any details about it, but I'll include the source code.<br><br>

	The program is called 'makeboot' and takes at least three parameters. The first one is the output file name. This can be 'a.img' in our case. The rest of the parameters are input files, read in order. We want our boot sector to be placed first and then our kernel.</h2>

		<h4>makeboot a.img bootsect.bin kernel.bin</h4>

	<h2><i><b>Tip for Windows users:</b> You can use the <b>copy</b> command to do this as well. Just execute the line: "<b>copy /b bootsect.bin +kernel.bin a.img</b>" and you don't have to use the makeboot-program.</i></h2>

	<h2>Just run bochs with a.img and this is what you should get:<br>

	<img src="bochs_running_tutorial_3.html"><br><br>

	<a href="tutor3.html">Download</a> the complete source for this tutorial, including makeboot and a .bat-file for compiling.<br><br>
	<a href="../tutorial_01/bochsrc.html">Download</a> my example configuration file for Bochs 2.0.2 - Win32.<br><br>
	<a href="../tutorial_01/bochsrc-2.html">Download</a> my example configuration file for Bochs (paths to the BIOS may have to be changed, if you're using another distributions than Win32 1.4.1).<br><br>

	Any comments, improvments or found errors? Mail me: <a href="mailto:gregor.brunmar@home.se">gregor.brunmar@home.se</a>.</h2>

	<table class="links" width=100%><tr>
		<td align=left>Move back to <a href="../tutorial_02/tutorial_02.html">tutorial 2</a></td>
		<td align=right>Move on to <a href="../tutorial_04/tutorial_04.html">tutorial 4</a></td>
	</tr></table><br>
</body>

<!-- Mirrored from bos.asmhackers.net/docs/booting/docs/tutorial_03.htm by HTTrack Website Copier/3.x [XR&CO'2013], Tue, 07 Oct 2014 11:22:01 GMT -->
</html>
